Overview

The ShinyStudio project is an orchestration of various open-source solutions with the goal of providing:

  • a secured, collaborative development environment for R, Python, PowerShell, and more.
  • a secured, convenient way to share apps and documents written in Shiny, RMarkdown, plain Markdown, or HTML.
  • easily reproducible, cross-platform setup leveraging Docker containers.

The ShinyStudio ecosystem includes:

Each component of the stack is run in a Docker container for reproducibility, scalability, and security. Only the NGINX port is exposed on the host system; all communication between ShinyProxy and other components happens inside an isolated Docker network.

The ShinyStudio “stack” includes the ShinyStudio image, which builds upon the rocker/verse image on DockerHub.

While this guide focuses on the stack, spin up the image in Bash or PowerShell with these commands:

Bash (Linux/Mac)

docker network create shinystudio-net && \
docker run --rm -it \
    --network shinystudio-net \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -e USERID=$UID \
    -e USER=$USER \
    -e PASSWORD=password \
    -e CONTENT_PATH="${HOME}/ShinyStudio/content" \
    -e SITE_NAME=shinystudio \
    -p 80:8080 \
    -e TAG=latest \
    dm3ll3n/shinystudio:latest


PowerShell

docker network create shinystudio-net;
docker run --rm -it `
    --network shinystudio-net `
    -v /var/run/docker.sock:/var/run/docker.sock `
    -e USERID=1000 `
    -e USER=$([environment]::UserName) `
    -e PASSWORD=password `
    -e CONTENT_PATH="/host_mnt/c/Users/$([environment]::UserName)/ShinyStudio/content" `
    -e SITE_NAME=shinystudio `
    -p 80:8080 `
    -e TAG=latest `
    dm3ll3n/shinystudio:latest

Notice the unique form of the path for the CONTENT_PATH variable required when in a Windows environment.


Getting Started

PreReqs:

Minimal setup:

# copy the setup files from version branch 0.5.0
git clone -b 0.5.0 https://github.com/dm3ll3n/ShinyStudio

# enter the directory.
cd ShinyStudio

# run certify to generate self-signed cert.
## Bash users run:
bash ./certify.sh

## Powershell users run:
pwsh ./certify.ps1

Important! As a crucial first step, log in to the job scheduler at https://<hostname>:8443 using the username admin and password administrator. Once in, go into settings and set a unique password.

Now, browse to http://<hostname> (e.g., http://localhost) to access ShinyStudio. On first launch, you will need to accept the warning about an untrusted certificate. See the customized setup to see how to request a trusted cert from LetsEncrypt.

The default logins are below.

username password
user user
dev developer
admin administrator

Customized setup:

Customized setup checklist:

Pre-Setup

  • Clone a version branch.
    • git clone -b 0.5.0 https://github.com/dm3ll3n/ShinyStudio.git myShinyStudio
    • Optionally, push to your own private repo.
      • git checkout -b master
      • git remote set-url origin https://github.com/<username>/myShinyStudio.git
      • git push
  • Set users/passwords in application.yml
  • Set CONTENT_PATH in .env
  • Set domain name in nginx.conf
  • Certify and launch.
    • bash certify.sh *or* pwsh certify.ps1

Post-Setup

  • Log in to cronicle at https://<hostname>:8443, change password.
    • Optionally, schedule jobs.
  • Login to shinystudio.
  • Set your own user-specific preferences in RStudio and VS Code.

The files essential to a customized configuration are described in more detail below:

.env

The docker-compose environment file. The project name, content path, and HTTP ports can be changed here.

Note that Docker volume names are renamed along with the project name, so be prepared to migrate or recreate data stored in Docker volumes when changing the project name.


application.yml

The ShinyProxy config file. Users can be added/removed here. Other configurations are available too, such as the site title and the ability to provide a non-standard landing page.

Using the provided template, you can assign users to the following groups with tiered access:

  • viewers: can only view content from “Apps & Reports”, “Documents”, and “Personal”.
  • developers: can view all site content and develop content with RStudio and VS Code.
  • administrators: can view and develop site content across multiple instances of ShinyStudio. Can also manage all user files.
Review the ShinyProxy configuration documentation for all options.


nginx.conf

The NGINX config file. Defines the accepted site name and what ports to listen on.

If you change the ports here, you must also change the ports defined in the .env file. Also, if you change the domain name, you must provide/generate a new certificate for it.


certify.sh

The script used to generate a self-signed cert, or to request a trusted cert from LetsEncrypt.

With no parameters, certify generates a self-signed cert for example.com (the default domain name defined in nginx.conf).

To generate a self-signed cert with another domain name, first edit the domain name in nginx.conf. Afterward, generate a new cert with:

bash ./certify.sh <domain>

# e.g., bash ./certify.sh www.shinystudio.com

If your server is accessible from the web, you can request a trusted certificate from LetsEncrypt. First, edit nginx.conf with your domain name, then request a new cert from LetsEncrypt like so:

bash ./certify.sh <domain> <email>

# e.g., bash ./certify.sh www.shinystudio.com you@email.com

CertBot will automatically renew your LetsEncrypt certificate.

To manage the services in the stack, use the native docker-compose commands, e.g.:

# stop all services.
docker-compose down

# start all services.
docker-compose up -d


Develop

Open either RStudio or VS Code and notice two important directories:

  • __ShinyStudio__
  • __Personal__

Files must be saved in either of these two directories in order to persist between sessions.

These two folders are shared between instances RStudio, VS Code, and Shiny Server. So, creating new content is as simple as saving a file to the appropriate directory.

Tools

The ShinyStudio image comes with…

  • R
  • Python 3 (via miniconda)
  • PowerShell

…and ODBC drivers for:

  • SQL Server
  • PostgresSQL
  • Cloudera Impala.

These are persistent because they are built into the image.

Persistent
__ShinyStudio__ directory Yes
__Personal__ directory Yes
Other directories No
Python (conda) Enviroments Yes
Python Packages Yes
R Libraries Yes
PowerShell Modules Yes
RStudio User Settings Yes
VS Code User Settings Yes
Installed Apps No, unless installed with conda
Installed Drivers No